# Checkbox

Checkboxes are used when a user needs to select one or more values from a series of options, or they can be used as a binary toggle.

## Import

```jsx
import { Checkbox, CheckboxField } from 'bumbag'
```

## Usage

```jsx-live
<Checkbox label="Check me" />
```

### Fields

You can also use the `<CheckboxField>` component, which internally has a [FieldWrapper](/form/field-wrapper) to wrap form controls such as labels, hint text and validation text.

It accepts a combination of [Checkbox props](/form/checkbox/#props) and [FieldWrapper props](/form/field-wrapper/#props).

```jsx-live
<CheckboxField
  checkboxLabel="Check me"
  label="Check below to subscribe"
/>
```

### Disabled

Make the checkbox disabled with the `disabled` prop.

```jsx-live
<Checkbox disabled label="Click me" />
<Checkbox checked disabled label="Click me" />
```

### Indeterminate

```jsx-live
<Checkbox label="Click me" checked indeterminate />
```

### States

A checkbox can use different states (as per palette) such as `danger`, `success` and `warning`.

```jsx-live
<Checkbox state="danger" label="Click me" />
<Checkbox state="success" label="Click me" />
<Checkbox state="warning" label="Click me" />
<Checkbox state="primary" label="Click me" />
```

### Controlled Usage

The previous examples are examples of uncontrolled usage. To control the value yourself, use a combination of `onChange` and `value`.

Note: Do not use `defaultValue` with controlled inputs!

```function-live
function Example() {
  const [checked, setChecked] = React.useState(true);

  return (
    <Checkbox
      label="Click me"
      checked={checked}
      onChange={e => setChecked(e.target.checked)}
    />
  );
}
```

## Accessibility

The `<Checkbox>` component follows the [WAI ARIA Checkbox Pattern](https://www.w3.org/TR/wai-aria-practices/#checkbox).

### Rules

- The checkbox must have a `label` prop to identify it's label. If a `label` prop is not provided, an `aria-label` or `aria-labelledby` prop can be specified.

#### Patterns

- The checkbox has a role of `checkbox`.
- The checkbox has an accessible label specified via the `label`, `aria-labelledby` or `aria-label` prop.
- When the checkbox has focus, pressing the <Key>Space</Key> key changes the state of the checkbox.

#### References

- [WAI ARIA Checkbox Pattern](https://www.w3.org/TR/wai-aria-practices/#checkbox)

## Props

### Checkbox Props

<!-- Automatically generated -->

**<Code fontSize="150" marginRight="major-1">autoFocus</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Automatically focus on the checkbox

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">checked</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Indicates if the checkbox is checked.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">inputProps</Code>** <Code fontSize="100" palette="primary">InputHTMLAttributes&#60;any&#62;</Code> 

Spreads the props onto the `<input>` element of the checkbox.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">defaultChecked</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Is the checkbox checked by default?

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">disabled</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Disables the checkbox

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">checkboxRef</Code>** <Code fontSize="100" palette="primary">((instance: any) =&#62; void) | RefObject&#60;any&#62;</Code> 

Forwards the ref to the checkbox.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">indeterminate</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Indicates if the checkbox is indeterminate.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">isRequired</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Makes the checkbox required and sets aria-invalid to true

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">label</Code>** <Code fontSize="100" palette="primary">string</Code> 

Checkbox label

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">name</Code>** <Code fontSize="100" palette="primary">string</Code> 

Sets the name of the checkbox.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">state</Code>** <Code fontSize="100" palette="primary">string</Code> 

State of the checkbox. Can be any color in the palette.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">value</Code>** <Code fontSize="100" palette="primary">string | boolean</Code> 

Initial value of the checkbox

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onBlur</Code>** <Code fontSize="100" palette="primary">(event: FocusEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when focus is lost

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onChange</Code>** <Code fontSize="100" palette="primary">(event: FormEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when checkbox has changed

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onFocus</Code>** <Code fontSize="100" palette="primary">(event: FocusEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when checkbox is focused

<Divider marginTop="major-2" marginBottom="major-2" />

### CheckboxField Props

<!-- Automatically generated -->

**<Code fontSize="150" marginRight="major-1">checkboxLabel</Code>** <Code fontSize="100" palette="primary">string</Code> 

Label for the checkbox

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">checkboxProps</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`Pick<BoxProps, "unstable_system"
  | "top"
  | "right"
  | "bottom"
  | "left"
  | "children"
  | "defaultChecked"
  | "defaultValue"
  | "suppressContentEditableWarning"
  | "suppressHydrationWarning"
  | ... 647 more ...
  | "themeKey"> & LocalCheckboxProps`}
</Code>

Additional props for the Checkbox component

<Divider marginTop="major-2" marginBottom="major-2" />

<details><Box use="summary" marginBottom="major-2">Inherits <strong><code>Checkbox</code></strong> props</Box>

**<Code fontSize="150" marginRight="major-1">autoFocus</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Automatically focus on the checkbox

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">checked</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Indicates if the checkbox is checked.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">inputProps</Code>** <Code fontSize="100" palette="primary">InputHTMLAttributes&#60;any&#62;</Code> 

Spreads the props onto the `<input>` element of the checkbox.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">defaultChecked</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Is the checkbox checked by default?

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">disabled</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Disables the checkbox

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">checkboxRef</Code>** <Code fontSize="100" palette="primary">((instance: any) =&#62; void) | RefObject&#60;any&#62;</Code> 

Forwards the ref to the checkbox.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">indeterminate</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Indicates if the checkbox is indeterminate.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">isRequired</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Makes the checkbox required and sets aria-invalid to true

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">label</Code>** <Code fontSize="100" palette="primary">string</Code> 

Checkbox label

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">name</Code>** <Code fontSize="100" palette="primary">string</Code> 

Sets the name of the checkbox.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">state</Code>** <Code fontSize="100" palette="primary">string</Code> 

State of the checkbox. Can be any color in the palette.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">value</Code>** <Code fontSize="100" palette="primary">string | boolean</Code> 

Initial value of the checkbox

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onBlur</Code>** <Code fontSize="100" palette="primary">(event: FocusEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when focus is lost

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onChange</Code>** <Code fontSize="100" palette="primary">(event: FormEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when checkbox has changed

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onFocus</Code>** <Code fontSize="100" palette="primary">(event: FocusEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when checkbox is focused

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
            

<details><Box use="summary" marginBottom="major-2">Inherits <strong><code>FieldWrapper</code></strong> props</Box>

**<Code fontSize="150" marginRight="major-1">children</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>
  | (({ elementProps }: { ...; }) => ReactNode)`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">description</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the description text of the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">hint</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the bottom hint text of the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">isOptional</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Sets the optional flag (and displays optional text) on the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">labelType</Code>** <Code fontSize="100" palette="primary">&#34;label&#34; | &#34;legend&#34;</Code> 

Sets the label type on the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">tooltip</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the tooltip of the field wrapper. Can be either a string, or a React component.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">tooltipTriggerComponent</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the tooltip trigger component.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">validationText</Code>** <Code fontSize="100" palette="primary">string</Code> 

Sets the bottom validation text of the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
            

<details><Box use="summary" marginBottom="major-2">Inherits <strong><code>Box</code></strong> props</Box>

**<Code fontSize="150" marginRight="major-1">use</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">className</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">alignX</Code>** <Code fontSize="100" palette="primary">&#34;right&#34; | &#34;left&#34; | &#34;center&#34;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">alignY</Code>** <Code fontSize="100" palette="primary">&#34;top&#34; | &#34;bottom&#34; | &#34;center&#34;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">variant</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">colorMode</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">overrides</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 96 more ...;
  Template?: TemplateThemeConfig;
}`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">elementRef</Code>** <Code fontSize="100" palette="primary">((instance: any) =&#62; void) | RefObject&#60;any&#62;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">themeKey</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
            

## Theming

### Checkbox

<Theme
  component={'Checkbox'}
  label="Click me"
  overrides={[
    'Checkbox.styles.base',
    'Checkbox.Icon.styles.base',
    'Checkbox.Label.styles.base',
    'Checkbox.HiddenInput.styles.base'
  ]} />

### CheckboxField

<Theme
  component={'CheckboxField'}
  label="Check below to subscribe"
  checkboxLabel="Click me"
  overrides={[
    'CheckboxField.styles.base'
  ]} />
